Getting Started

The quick start below is all you need to be talking on IRC. Everything after it is optional, and grouped by what you are trying to do rather than by which settings screen it lives on.

Quick start

Pick a network, connect, join a channel.

Add a network

Open Networks from the main menu, configure one of the default networks or tap Add.
Enter a display name (e.g. somenet), then the server host and port. Most TLS-enabled servers use port 6697
Leave TLS enabled. It encrypts your connection and virtually every modern IRC server supports it.
Set your nickname, and optionally an alternate nick, username and real name.

Tip: When modifying or adding a network, slide "Show in network sidebar". Tap the star icon on a network row to pin it to the top of the Networks list.

Connect

Tap the network row and choose Connect. Server messages appear in the network's server buffer: you'll see CAP negotiation, then a Registered message confirming your effective nickname and the IRCv3 capabilities that were agreed.

Turn on Auto-connect on startup in network settings to skip this step in future. Staying connected.

Join a channel

/join #channel, or /join #channel key for key-protected channels.
/list opens a searchable browser of every channel on the network.
To join automatically on every connect, add channels to the auto-join list in network settings. Keys are supported.

Tip: tap the X on any buffer in the sidebar to part and close it in one go.

Signing in to your account

If you've registered your nickname with the network's services, HexDroid can identify you automatically. SASL does it during the connection handshake, before you're visible on the network; post-connect commands do it afterwards, for servers that don't offer SASL.

SASL

Enable SASL in network settings under Authentication. Because it runs during the handshake, you're identified before you join anything. no /ns IDENTIFY needed, and no chance of being seen under an unidentified nick.

Mechanism	How it works	When to use
PLAIN	Username + password, base64-encoded	Most common; safe over TLS
SCRAM-SHA-256	Cryptographic challenge/response	Best option when available
EXTERNAL	Authenticates using a TLS client certificate fingerprint	With CertFP, below

authcid is your services account name, usually your registered nick. Leave it blank to use your current nick.

If SASL fails the connection still goes ahead, but you won't be identified. Check your authcid and password, or see Troubleshooting → SASL.

Client certificates (CertFP)

CertFP identifies you by your certificate's fingerprint instead of a password. HexDroid accepts .pem / .crt and PKCS#12 (.p12 / .pfx).

In network settings, find TLS Client Certificate and tap Import certificate.
Select your file and enter the certificate password, or leave it blank for unprotected certs.
Register the fingerprint with services: /ns CERT ADD on most networks.
Set the SASL mechanism to EXTERNAL.

To convert a .crt + .key pair to PKCS#12:

openssl pkcs12 -export -in cert.crt -inkey cert.key -out cert.p12

When the server has no SASL

Post-connect commands run any slash commands once registration completes. Useful for identifying with NickServ, ghosting a stale session, or joining a restricted channel. Set them in network settings under Post-connect commands, one per line, with a delay in seconds — some servers need a moment before they'll accept service commands.

/ns GHOST MyOldNick password   # kill old session
/nick MyNick                    # reclaim the nick
/join #ops                      # join restricted channel

An irssi-style ;wait suffix delays everything after it:

/join #idlerpg;wait 6                      join idlerpg but wait 6 seconds

Staying connected

IRC has no server-side inbox: if your client is offline, you miss what was said. These settings are what make HexDroid behave like a messaging app rather than a terminal you have to keep open.

Background connection

Turn on Keep alive in background in Settings › Connection. HexDroid then holds your connections open through an Android foreground service, so you can close the app and still get highlight notifications. Android requires a persistent notification while that service runs — that's the notification you'll see in your shade.

If a connection drops, auto-reconnect retries with exponential backoff. It's on by default; the initial delay is configurable in Settings.

Battery optimisation. Some manufacturers kill background processes aggressively. If HexDroid disconnects after you close it, see Troubleshooting → Always connected for device-specific fixes.

Notifications

HexDroid notifies you when your nickname is mentioned in any channel, when a private message arrives, and when any custom highlight word you've defined in Settings appears. Custom words are case-insensitive.

On Android 13 and later you'll be asked for notification permission on first run; you can change it afterwards under Android Settings › Apps › HexDroid › Notifications. Sound and vibration intensity (Low / Medium / High) live in HexDroid's own Settings screen.

Catching up on what you missed

On servers supporting chathistory or draft/chathistory — and on most bouncers — HexDroid fetches recent messages automatically when you join a channel. Set how many under Settings › History limit (default 50). Replayed messages are deduplicated by msgid, so nothing appears twice even across reconnects.

By default, history doesn't count as unread and doesn't trigger notifications. Both are switchable in Settings if you'd rather it did.

Security and privacy

TLS is on by default and needs no setup. These two go further: pinning protects you if a server's certificate is swapped, and a proxy hides which server you're talking to. For encrypting the messages themselves, see the encryption guide.

Certificate pinning (TOFU)

Since v1.5.5 HexDroid uses Trust On First Use pinning rather than a blanket "allow invalid certificates" toggle, so you get real protection without needing a CA-signed certificate. On the first connect to a server it records the SHA-256 certificate fingerprint; on every connect after that, it verifies it. If the fingerprint changes, the connection is aborted with a warning.

Self-signed certificates work fine — the fingerprint is learned on first connect, and there's nothing to import into your device's CA store.

Fingerprint mismatch? If you trust the new certificate — the admin renewed it, say — clear the pin under Network settings › TLS › Reset pinned certificate, then reconnect to pin the new one.

Proxy and Tor

Each network can route through a SOCKS proxy, configured per-network under Proxy in network settings. The same proxy carries that network's DCC transfers. A proxy counts as active once you pick a type other than None and give a valid host and a port between 1 and 65535.

Type	What it does	Remote DNS
SOCKS5	RFC 1928, with optional username / password auth (RFC 1929). Hostnames are sent to the proxy as a domain name for it to resolve.	Yes
SOCKS4a	The `a` extension to SOCKS4 sends the literal hostname for the proxy to resolve. No authentication.	Yes
None	Direct connection (default).	—

To connect over Tor: install and start Orbot (or another local Tor daemon), set Proxy type to SOCKS5 and host to 127.0.0.1, then set port to 9050 for Orbot or 9150 for the Tor Browser daemon. Leave authentication blank — it's SOCKS5-only in any case.

No DNS leak. Both SOCKS5 and SOCKS4a resolve the destination hostname at the proxy, so the server's address is never looked up by your device's resolver. Pair Tor with a network offering a .onion address for end-to-end anonymity.

Using a bouncer

A bouncer stays connected on your behalf and replays what you missed. Turn on Bouncer mode in network settings, then pick a Bouncer type — HexDroid composes the correct username syntax for you. This matters: soju and ZNC use different orderings of / and @, and the wrong one silently misroutes the connection.

Bouncer types

soju composes user/network@clientid.
ZNC composes user@clientid/network.
Generic composes user/network and Client ID is ignored.
None applies no bouncer-specific syntax. Use it when you hand-roll the username yourself, or when you want Bouncer mode's other behaviours without routing through a specific upstream.

Network name and Client ID

Set Network name to the upstream network as configured on your bouncer (libera, oftc, and so on). Set Client ID to a short identifier for this device — phone, desktop. That's what enables per-client buffers on ZNC (the clientbuffer module) and per-client history on soju, so each device keeps its own read position and unread counts.

Two shortcuts save you typing: /znc <command> is shorthand for /msg *status <command>, and /bouncerserv <command> (alias /bnc) for /msg BouncerServ <command>.

What Bouncer mode changes

Auto-join is skipped — the bouncer already keeps you in your channels server-side.
The MOTD is not suppressed, because a bouncer's MOTD usually carries status information.
BouncerServ and *status replies go to the server buffer instead of opening a query window.
On ZNC, znc.in/server-time-iso and znc.in/playback are negotiated.
On soju, soju.im/bouncer-networks, soju.im/bouncer-networks-notify and soju.im/read are negotiated.

Moving to a new device

HexDroid exports every network configuration and app setting to a single JSON file.

Go to Settings › Backup & Restore.
Tap Export and choose where to save the file.
On the new device, tap Import and select it. Your networks and settings are re-created.

SASL passwords and TLS client certificates are not exported, deliberately. You'll need to re-enter those after restoring.